<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Eigen: Structures Having Eigen Members</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
  $(document).ready(function() { init_search(); });
/* @license-end */
</script>
<script type="text/x-mathjax-config">
  MathJax.Hub.Config({
    extensions: ["tex2jax.js", "TeX/AMSmath.js", "TeX/AMSsymbols.js"],
    jax: ["input/TeX","output/HTML-CSS"],
});
</script>
<script type="text/javascript" async="async" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="eigendoxy.css" rel="stylesheet" type="text/css">
<!--  -->
<script type="text/javascript" src="eigen_navtree_hacks.js"></script>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="Eigen_Silly_Professor_64x64.png"/></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname"><a href="http://eigen.tuxfamily.org">Eigen</a>
   &#160;<span id="projectnumber">3.4.90 (git rev 67eeba6e720c5745abc77ae6c92ce0a44aa7b7ae)</span>
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.svg"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
/* @license-end */
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function(){initNavTree('group__TopicStructHavingEigenMembers.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Structures Having Eigen Members<div class="ingroups"><a class="el" href="group__DenseMatrixManipulation__chapter.html">Dense matrix and array manipulation</a> &raquo; <a class="el" href="group__DenseMatrixManipulation__Alignement.html">Alignment issues</a></div></div>  </div>
</div><!--header-->
<div class="contents">
<h1><a class="anchor" id="StructHavingEigenMembers_summary"></a>
Executive Summary</h1>
<p>If you define a structure having members of <a class="el" href="group__TopicFixedSizeVectorizable.html">fixed-size vectorizable Eigen types</a>, you must ensure that calling operator new on it allocates properly aligned buffers. If you're compiling in <span class="cpp17">[c++17]</span> mode only with a sufficiently recent compiler (e.g., GCC&gt;=7, clang&gt;=5, MSVC&gt;=19.12), then everything is taken care by the compiler and you can stop reading.</p>
<p>Otherwise, you have to overload its <code>operator new</code> so that it generates properly aligned pointers (e.g., 32-bytes-aligned for Vector4d and AVX). Fortunately, Eigen provides you with a macro <code>EIGEN_MAKE_ALIGNED_OPERATOR_NEW</code> that does that for you.</p>
<h1><a class="anchor" id="StructHavingEigenMembers_what"></a>
What kind of code needs to be changed?</h1>
<p>The kind of code that needs to be changed is this:</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>Foo</div>
<div class="line">{</div>
<div class="line">  ...</div>
<div class="line">  <a class="code" href="classEigen_1_1Matrix.html">Eigen::Vector2d</a> v;</div>
<div class="line">  ...</div>
<div class="line">};</div>
<div class="line"> </div>
<div class="line">...</div>
<div class="line"> </div>
<div class="line">Foo *foo = <span class="keyword">new</span> Foo;</div>
<div class="ttc" id="aclassEigen_1_1Matrix_html"><div class="ttname"><a href="classEigen_1_1Matrix.html">Eigen::Matrix</a></div><div class="ttdoc">The matrix class, also used for vectors and row-vectors.</div><div class="ttdef"><b>Definition:</b> Matrix.h:182</div></div>
</div><!-- fragment --><p>In other words: you have a class that has as a member a <a class="el" href="group__TopicFixedSizeVectorizable.html">fixed-size vectorizable Eigen object</a>, and then you dynamically create an object of that class.</p>
<h1><a class="anchor" id="StructHavingEigenMembers_how"></a>
How should such code be modified?</h1>
<p>Very easy, you just need to put a <code>EIGEN_MAKE_ALIGNED_OPERATOR_NEW</code> macro in a public part of your class, like this:</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>Foo</div>
<div class="line">{</div>
<div class="line">  ...</div>
<div class="line">  <a class="code" href="classEigen_1_1Matrix.html">Eigen::Vector4d</a> v;</div>
<div class="line">  ...</div>
<div class="line">public:</div>
<div class="line">  EIGEN_MAKE_ALIGNED_OPERATOR_NEW</div>
<div class="line">};</div>
<div class="line"> </div>
<div class="line">...</div>
<div class="line"> </div>
<div class="line">Foo *foo = <span class="keyword">new</span> Foo;</div>
</div><!-- fragment --><p>This macro makes <code>new Foo</code> always return an aligned pointer.</p>
<p>In <span class="cpp17">[c++17]</span>, this macro is empty.</p>
<p>If this approach is too intrusive, see also the <a class="el" href="group__TopicStructHavingEigenMembers.html#StructHavingEigenMembers_othersolutions">other solutions</a>.</p>
<h1><a class="anchor" id="StructHavingEigenMembers_why"></a>
Why is this needed?</h1>
<p>OK let's say that your code looks like this:</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>Foo</div>
<div class="line">{</div>
<div class="line">  ...</div>
<div class="line">  <a class="code" href="classEigen_1_1Matrix.html">Eigen::Vector4d</a> v;</div>
<div class="line">  ...</div>
<div class="line">};</div>
<div class="line"> </div>
<div class="line">...</div>
<div class="line"> </div>
<div class="line">Foo *foo = <span class="keyword">new</span> Foo;</div>
</div><!-- fragment --><p>A <a class="el" href="group__matrixtypedefs.html#ga9b2fcb53776a2829871f8a49009bef0b" title="4×1 vector of type double.">Eigen::Vector4d</a> consists of 4 doubles, which is 256 bits. This is exactly the size of an AVX register, which makes it possible to use AVX for all sorts of operations on this vector. But AVX instructions (at least the ones that Eigen uses, which are the fast ones) require 256-bit alignment. Otherwise you get a segmentation fault.</p>
<p>For this reason, Eigen takes care by itself to require 256-bit alignment for <a class="el" href="group__matrixtypedefs.html#ga9b2fcb53776a2829871f8a49009bef0b" title="4×1 vector of type double.">Eigen::Vector4d</a>, by doing two things: </p><ul>
<li>Eigen requires 256-bit alignment for the <a class="el" href="group__matrixtypedefs.html#ga9b2fcb53776a2829871f8a49009bef0b" title="4×1 vector of type double.">Eigen::Vector4d</a>'s array (of 4 doubles). This is done with the <a href="https://en.cppreference.com/w/cpp/keyword/alignas">alignas</a> keyword. </li>
<li>Eigen overloads the <code>operator new</code> of <a class="el" href="group__matrixtypedefs.html#ga9b2fcb53776a2829871f8a49009bef0b" title="4×1 vector of type double.">Eigen::Vector4d</a> so it will always return 256-bit aligned pointers. (removed in <span class="cpp17">[c++17]</span>)</li>
</ul>
<p>Thus, normally, you don't have to worry about anything, Eigen handles alignment of operator new for you...</p>
<p>... except in one case. When you have a <code>class Foo</code> like above, and you dynamically allocate a new <code>Foo</code> as above, then, since <code>Foo</code> doesn't have aligned <code>operator new</code>, the returned pointer foo is not necessarily 256-bit aligned.</p>
<p>The alignment attribute of the member <code>v</code> is then relative to the start of the class <code>Foo</code>. If the <code>foo</code> pointer wasn't aligned, then <code>foo-&gt;v</code> won't be aligned either!</p>
<p>The solution is to let <code>class Foo</code> have an aligned <code>operator new</code>, as we showed in the previous section.</p>
<p>This explanation also holds for SSE/NEON/MSA/Altivec/VSX targets, which require 16-bytes alignment, and AVX512 which requires 64-bytes alignment for fixed-size objects multiple of 64 bytes (e.g., <a class="el" href="group__matrixtypedefs.html#ga31c5fac458c04196a36b36b5e51127ff" title="4×4 matrix of type double.">Eigen::Matrix4d</a>).</p>
<h1><a class="anchor" id="StructHavingEigenMembers_movetotop"></a>
Should I then put all the members of Eigen types at the beginning of my class?</h1>
<p>That's not required. Since Eigen takes care of declaring adequate alignment, all members that need it are automatically aligned relatively to the class. So code like this works fine:</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>Foo</div>
<div class="line">{</div>
<div class="line">  <span class="keywordtype">double</span> x;</div>
<div class="line">  <a class="code" href="classEigen_1_1Matrix.html">Eigen::Vector4d</a> v;</div>
<div class="line"><span class="keyword">public</span>:</div>
<div class="line">  EIGEN_MAKE_ALIGNED_OPERATOR_NEW</div>
<div class="line">};</div>
</div><!-- fragment --><p>That said, as usual, it is recommended to sort the members so that alignment does not waste memory. In the above example, with AVX, the compiler will have to reserve 24 empty bytes between <code>x</code> and <code>v</code>.</p>
<h1><a class="anchor" id="StructHavingEigenMembers_dynamicsize"></a>
What about dynamic-size matrices and vectors?</h1>
<p>Dynamic-size matrices and vectors, such as <a class="el" href="group__matrixtypedefs.html#ga8554c6170729f01c7572574837ecf618" title="Dynamic×1 vector of type double.">Eigen::VectorXd</a>, allocate dynamically their own array of coefficients, so they take care of requiring absolute alignment automatically. So they don't cause this issue. The issue discussed here is only with <a class="el" href="group__TopicFixedSizeVectorizable.html">fixed-size vectorizable matrices and vectors</a>.</p>
<h1><a class="anchor" id="StructHavingEigenMembers_bugineigen"></a>
So is this a bug in Eigen?</h1>
<p>No, it's not our bug. It's more like an inherent problem of the c++ language specification that has been solved in c++17 through the feature known as <a href="http://wg21.link/p0035r4">dynamic memory allocation for over-aligned data</a>.</p>
<h1><a class="anchor" id="StructHavingEigenMembers_conditional"></a>
What if I want to do this conditionally (depending on template parameters) ?</h1>
<p>For this situation, we offer the macro <code>EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF(NeedsToAlign)</code>. It will generate aligned operators like <code>EIGEN_MAKE_ALIGNED_OPERATOR_NEW</code> if <code>NeedsToAlign</code> is true. It will generate operators with the default alignment if <code>NeedsToAlign</code> is false. In <span class="cpp17">[c++17]</span>, this macro is empty.</p>
<p>Example:</p>
<div class="fragment"><div class="line"><span class="keyword">template</span>&lt;<span class="keywordtype">int</span> n&gt; <span class="keyword">class </span>Foo</div>
<div class="line">{</div>
<div class="line">  <span class="keyword">typedef</span> <a class="code" href="classEigen_1_1Matrix.html">Eigen::Matrix&lt;float,n,1&gt;</a> <a class="code" href="group__matrixtypedefs.html#ga2623c0d4641dda067fbdb9a009ef0c91">Vector</a>;</div>
<div class="line">  <span class="keyword">enum</span> { NeedsToAlign = (<span class="keyword">sizeof</span>(<a class="code" href="group__matrixtypedefs.html#ga2623c0d4641dda067fbdb9a009ef0c91">Vector</a>)%16)==0 };</div>
<div class="line">  ...</div>
<div class="line">  <a class="code" href="group__matrixtypedefs.html#ga2623c0d4641dda067fbdb9a009ef0c91">Vector</a> v;</div>
<div class="line">  ...</div>
<div class="line">public:</div>
<div class="line">  EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF(NeedsToAlign)</div>
<div class="line">};</div>
<div class="line"> </div>
<div class="line">...</div>
<div class="line"> </div>
<div class="line">Foo&lt;4&gt; *foo4 = <span class="keyword">new</span> Foo&lt;4&gt;; <span class="comment">// foo4 is guaranteed to be 128bit-aligned</span></div>
<div class="line">Foo&lt;3&gt; *foo3 = <span class="keyword">new</span> Foo&lt;3&gt;; <span class="comment">// foo3 has only the system default alignment guarantee</span></div>
<div class="ttc" id="agroup__matrixtypedefs_html_ga2623c0d4641dda067fbdb9a009ef0c91"><div class="ttname"><a href="group__matrixtypedefs.html#ga2623c0d4641dda067fbdb9a009ef0c91">Eigen::Vector</a></div><div class="ttdeci">Matrix&lt; Type, Size, 1 &gt; Vector</div><div class="ttdoc">[c++11] Size×1 vector of type Type.</div><div class="ttdef"><b>Definition:</b> Matrix.h:544</div></div>
</div><!-- fragment --><h1><a class="anchor" id="StructHavingEigenMembers_othersolutions"></a>
Other solutions</h1>
<p>In case putting the <code>EIGEN_MAKE_ALIGNED_OPERATOR_NEW</code> macro everywhere is too intrusive, there exists at least two other solutions.</p>
<h2><a class="anchor" id="othersolutions1"></a>
Disabling alignment</h2>
<p>The first is to disable alignment requirement for the fixed size members: </p><div class="fragment"><div class="line"><span class="keyword">class </span>Foo</div>
<div class="line">{</div>
<div class="line">  ...</div>
<div class="line">  <a class="code" href="classEigen_1_1Matrix.html">Eigen::Matrix&lt;double,4,1,Eigen::DontAlign&gt;</a> v;</div>
<div class="line">  ...</div>
<div class="line">};</div>
</div><!-- fragment --><p> This <code>v</code> is fully compatible with aligned <a class="el" href="group__matrixtypedefs.html#ga9b2fcb53776a2829871f8a49009bef0b" title="4×1 vector of type double.">Eigen::Vector4d</a>. This has only for effect to make load/stores to <code>v</code> more expensive (usually slightly, but that's hardware dependent).</p>
<h2><a class="anchor" id="othersolutions2"></a>
Private structure</h2>
<p>The second consist in storing the fixed-size objects into a private struct which will be dynamically allocated at the construction time of the main object:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>Foo_d</div>
<div class="line">{</div>
<div class="line">  EIGEN_MAKE_ALIGNED_OPERATOR_NEW</div>
<div class="line">  <a class="code" href="group__matrixtypedefs.html#ga9b2fcb53776a2829871f8a49009bef0b">Vector4d</a> v;</div>
<div class="line">  ...</div>
<div class="line">};</div>
<div class="line"> </div>
<div class="line"> </div>
<div class="line"><span class="keyword">struct </span>Foo {</div>
<div class="line">  Foo() { init_d(); }</div>
<div class="line">  ~Foo() { <span class="keyword">delete</span> d; }</div>
<div class="line">  <span class="keywordtype">void</span> bar()</div>
<div class="line">  {</div>
<div class="line">    <span class="comment">// use d-&gt;v instead of v</span></div>
<div class="line">    ...</div>
<div class="line">  }</div>
<div class="line"><span class="keyword">private</span>:</div>
<div class="line">  <span class="keywordtype">void</span> init_d() { d = <span class="keyword">new</span> Foo_d; }</div>
<div class="line">  Foo_d* d;</div>
<div class="line">};</div>
<div class="ttc" id="agroup__matrixtypedefs_html_ga9b2fcb53776a2829871f8a49009bef0b"><div class="ttname"><a href="group__matrixtypedefs.html#ga9b2fcb53776a2829871f8a49009bef0b">Eigen::Vector4d</a></div><div class="ttdeci">Matrix&lt; double, 4, 1 &gt; Vector4d</div><div class="ttdoc">4×1 vector of type double.</div><div class="ttdef"><b>Definition:</b> Matrix.h:501</div></div>
</div><!-- fragment --><p>The clear advantage here is that the class <code>Foo</code> remains unchanged regarding alignment issues. The drawback is that an additional heap allocation will be required whatsoever. </p>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Thu Apr 21 2022 13:07:55 for Eigen by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.9.1 </li>
  </ul>
</div>
</body>
</html>
